Web Services API Guide

System architecture

Request/response overview

GET requests

POST/PUT requests

JSON responses

Object types and subtypes

Form field types

Common form field IDs and types

Access rights

Please note

OpenText is not responsible for providing support for the creation and maintenance of custom forms or applications.

System architecture

Overview

The FirstClass Web Services server (FirstClass web server) is a Python implementation of a web server that facilitates access to FirstClass server data and functionality. The FirstClass web client (or any other web-based client) uses HTML 5.0 to communicate with the FirstClass web server. Requests issued to the FirstClass web server are translated into the FirstClass-proprietary protocol FCP and sent to the FirstClass server for processing. The FirstClass server responses are also encapsulated in the FCP protocol, which is then processed by the FirstClass web server and subsequently sent back to the web client as HTML pages, JSON data, CSS style data and/or JavaScript code.

The FirstClass web server also supports WebSocket and/or AJAX connections to facilitate live web client updates with changes that occurred on the FirstClass server (new mail notifications, calendar alarm reminders, container content changes, and so on).



Tools and technology

The FirstClass web server is implemented in the Python programming language (2.7/2.6) as a WSGI server application. It can run as an application with any WSGI server. To run it with any of the available WSGI servers, simply instantiate the WSGI server and pass in the FirstClass web server application method fcweb.server.application.

The FirstClass web server uses the Mako (0.7.2) template library to generate dynamic HTML content. Mako enables the embedding of Python code in the HTML templates to create dynamic HTML content. Users who wish to customize their HTML templates and content will have to use Mako to do so. The FirstClass web server uses elements of HTML 5.0, so web clients using this API should support HTML 5.0 features to draw the full benefit from the API.

Structure

The FirstClass web server directory structure is shown below:



Directory description:

The following directories represent separate Python packages. These directories are at the same level as fcws.

Localization and customization

The FirstClass web server provides mechanisms for localization and customization. Basic language localization is done automatically by the FirstClass web server based on the language settings in the web browser Accept_Language HTTP header. Additionally, this API provides a JSON mechanism to override browser settings or supply an independent parameter for language localization for each session. Automated applications using this API can set the desired language at login time in two ways:

The FirstClass web server can additionally be customized and/or localized by providing custom and localized html templates in directories localized/<lang code>/html and localized/<lang code>/user/html. The template loader will search for a given template first in localized/<lang code>/user/html, then in localized/<lang code>/html, and finally in fcws/html. The first occurrence of a given template name will be used given the specified search order. Searching the described paths for a requested template as well as loading and rendering of the template is done automatically by the template loader.

Any localization and/or customization of JavaScript code residing in the localized/<language code>/js directory requires manual loading of needed JavaScript files. This can be accomplished by loading any custom HTML template that contains JavaScript loading code. Before rendering by Mako, each HTML template (default or custom) will be passed a Python variable localizedRelativePath which defines the path to the customized and/or localized localized/<language code> directory. This path can be used by the custom template to load any customized and/or localized files. HTML template code loading a specific customized and/or localized JavaScript file could be as follows:

<script type="text/javascript" src="${localizedRelativePath}/js/myfile.js"></script>

where ${localizedRelativePath} is a Mako syntax for specifying a Python variable in the source HTML template. Upon template compilation by Mako, the resultant, compiled template will contain the correct path to the file myfile.js.

What happens with an update

When you update the FirstClass web server, the currently installed version is archived in case resources from it need to be restored.

When you have localized/customized resources, one of two things will happen to those resources, depending on the type of update.

If the update is a nontransitional release (for example, 12.1.0 to 12.1.1), all localized/customized resources are restored to the updated version. This includes images, css and themes, and HTML. Because the installer can't tell if sprites were customized, it restores the old sprites to the updated version and creates a new_sprites folder that contains the new sprites for the updated version. You can simply use the old sprites if you customized them. If you didn't, you can copy in the new sprites.

If the update is a transitional release (for example, 12.1.1 to 12.2.0 or 16.0.0), all localized/customized resources are stored in a folder called localized_a.b.c (for example, localized_12.1.1). The updated version is completely new, with no localized/customized resources.

Request/response overview

WebID and FCP URL

The FirstClass web server uses "webID" to uniquely identify objects on the FirstClass server. WebID is a hex value of major ID (8 bytes) and minor ID (4 bytes) as a string that is concatenated with the string representation of the FirstClass object type (1 byte) and sub-type (1 byte) for a total string length of 28 characters (14 bytes).

If the major ID is set and is of type str, webID is set to the string representation of that binary value which is the actual object message ID. This used for all regular and persistent objects.

If the major ID is set and is of type unicode, webID is set to that value, with minor ID set to zero. This used for named objects such as Desktop and Directory.

If the major ID is set and is of type int, webID is set to the string representation of that integer value which is the FirstClass object ID and usually represents objects that are opened without major ID and/or minor ID, such as Directory and Who's Online. Major ID can also be a CID for users since they have CIDs instead of message IDs.

If the major ID is not set, an object name hash is calculated and its string representation is placed in the major ID. This is usually used for objects with no message ID and/or object ID, such as attachments. Minor ID is a 4 byte integer, where the low 2 bytes are a mapping item Outgoing status bit to distinguish messages sent to self from received messages sent to self. The upper two bytes of minor ID space are reserved for future identification of item uniqueness by some additional criteria.

FirstClass objects have a persistent webID throughout their entire lifetime on the FirstClass server. Note that some objects are created and exist only temporarily during a user session. Once destroyed/closed they will no longer exist and as such will not have a persistent webID. In other words, objects such as folders, conferences, messages, events, contacts, and documents (any long-lasting objects that are independent of user sessions) will have a persistent webID that is valid for any user on any session at any time, as long as that object exists on the FirstClass server, regardless of whether it is opened by anyone or not.

On the other hand, temporary objects such as Directory lookups, Who's Online lookups, profiles, and chats, or positional-indexed objects such as message recipients and attachments, will have a webID that is persistent only during that object's (or parent object's) opened state. Basically, their webID will be valid only during their lifetime in the current session.

An FCP URL is just an HTTP request URL path consisting of webIDs defining the full path to the last object, much like a normal file-path. Each FCP URL path must begin with /v1/FCP/ to distinguish local resources from FirstClass resources. An example of an FCP URL path is:

/v1/FCP/    DeskTop webID            /      MailBoxwebID          /     Message 1 webID
/v1/FCP/DeskTop000000000000000000000/80000000000000010002D28E0000/011000000009EC4A000219230000

The above FCP path contains also the API version number as the first element of the path. This document describes FC Web Service API Version 1.

GET request overview

All requests to the FirstClass web server for data retrieval from the FirstClass server are done by issuing HTTP GET requests. An HTTP GET request has the following general format:

GET <path>?<query>

where path can be either a path to a local resource on the FirstClass web server, such as an image, icon or sound file (for example, /image/icons/login.ico) or a FirstClass server object-specific (FCP) path consisting of FCP webID values specifying a path to a specific object on the FirstClass server.

The query value qualifies the path in terms of what exactly and in what form something is being retrieved from the FirstClass server. For example, it may contain a date range for retrieval of events from a calendar object or the number of items to retrieve from a container. All URL path and query keywords are case sensitive. Query keyword values are not case sensitive. For example, in this URL:

GET/v1/FCP/011000000009EC4A000219230000?Page=FIRST&Size=100&Retrieve=LIST&Filter=0x8000

query keywords Page, Size, Retrieve and Filter are case sensitive. Values FIRST and LIST are not case sensitive.

POST / PUT request overview

All requests to the FirstClass web server for data storage to the FirstClass server are done by issuing HTTP POST and PUT requests. An HTTP POST/PUT request has one of the following general formats:

POST
<request body - multipart forms data>

or

POST /?JSON
<request body - JSON data in UTF-8>

where JSON data in UTF-8 contains the JSON specification of what data to store in the FirstClass server.

DELETE request overview

HTTP DELETE request is used to delete a single object on the FirstClass Server. DELETE request has the following general format:

DELETE <path>

For example, deleting an object with the webID 011000000009EC4A000219230000:

DELETE /v1/FCP/011000000009EC4A000219230000

To delete multiple objects and or fields in FirstClass objects use POST/PUT requests with JSON.

Responses

Depending on the request type, responses are returned either as HTML documents or as JSON data encoded in UTF-8. Returned HTML documents are files the FirstClass web server originally stored or subsequently customized for a given implementation of the FirstClass web server. Requests that originally return HTML documents can be modified to return only JSON data. This is accomplished by supplying a request query parameter ReplyAsJSON in the request URL, providing for automated (non-UI-based) applications to use this API. A number of requests will return JSON data by default and need not have the ReplyAsJSON query parameter embedded in the URL. These requests and corresponding JSON replies are defined below. This document concentrates primarily on JSON responses.

Same origin policy implications and JSONP requests/responses

Due to browser security restrictions, most requests are subject to the same origin policy. The request can't successfully retrieve data from a different domain, subdomain, or protocol. This means that any requests to this API from a web browser application from a different domain, subdomain, or protocol will be denied a request to the FirstClass web server. To overcome this browser restriction, this API provides a JSONP mechanism that enables data to be submitted/retrieved as part of a script request which does not fall under the same origin policy restriction. Note that this restriction does not apply if the application accessing the FirstClass web server API is not browser based, since same origin policy is a browser-enforced policy. Non-web browser applications or browser applications in the FirstClass web server domain can use unrestricted API features to retrieve HTML pages and/or JSON data.

When using JSONP with this API, only JSON data will be retrieved. No HTML pages can be retrieved. To use JSONP to retrieve data, an application must issue a GET request as follows:

GET <FCP URL>?callback=<callback function name>&JSON

where <FCP URL> is any valid FCP URL as described in this API document and <callback function name> specifies the JavaScript callback function name that wraps the JSON response. The response to this request is going to be a JavaScript consisting of a JSON reply wrapped in the callback function name function. For example, a request to open and retrieve a contact with webID 8000000333030000300300000003 may look like:

GET /v1/FCP/8000000333030000300300000003?callback=myContact&JSON

and the response would be a JavaScript function encoded in UTF-8:

myContact( {"contact":{"Last Name":"Doe","First Name":"John","Phone":"444 555 6666"}})

Upon receiving this response, the application should invoke JavaScript instead of the JSON parser.

To submit JSON data via a JSONP GET request, simply set the value of the JSON URL parameter to the JSON data encoded in UTF-8 and properly quoted as per URL request:

GET <FCP URL>?callback=<callback function name>&JSON=<url quoted JSON data in UTF-8>

This request will be interpreted by the FirstClass web server as:

POST /?JSON
<request body - JSON data in UTF-8>

The reply, however, will be JSON wrapped in the JavaScript callback function name as specified in the GET request.

NOTE: When sending base64 encoded JSON data via JSONP, resultant JSON is embedded in a GET request URL and should also be "safe-url" encoded since base64 encoded data may contain invalid URL characters.

Validation keys

Since JSONP POST-ing of data permits cross-domain modification of web-site data, it is inherently not secure and opens a web site to potentially malicious attacks. To make JSONP embedded POST requests secure, FirstClass Web Services uses validation keys which must be submitted with every JSONP embedded POST request. A set of 10 validation keys are returned to the client in the login-reply JSON packet. Every time a JSONP embedded POST request is issued, the request url must contain one of the validation keys from a pool of valid keys. The url will be of the following format:

GET <FCP URL>?callback=<callback function name>&JSON=<url quoted JSON data in UTF-8>&VKey=123456789

This validation key must be verified by the server before proceeding with the execution of the request. Once verified and consumed, this validation key should be discarded by both client and server. The server will supply to the client a new validation key in the JSON response status.

GET requests

FirstClass web server GET requests are used to retrieve specific data from the FirstClass web server or FirstClass server. Responses to GET requests are either standard HTML pages for the FirstClass web client application or data in JSON format. Responses consisting of standard HTML pages can be replaced with the pure JSON data equivalent of each HTML page by supplying a URL query parameter ReplyAsJSON anywhere in the query. This document will describe primarily JSON responses to all GET and POST requests.

Opening objects

Absolute path to open object webIDN

Only DeskTop needs to be open

/v1/FCP/DeskTop000000000000000000000/webID1/webID2/...webIDN

Relative path to open webIDN

Parent object webID1 needs to be open

/v1/FCP/webID1/webIDN

Opening (downloading) files/attachments from the FirstClass server

/v1/FCP/webID1/webID2/...webIDN/

Examples:

GET /v1/FCP/DeskTop000000000000000000000/80000000000000010002D28E0000/011000000009EC4A000219230000
GET /v1/FCP/80000000000000010002D28E0000/011000000009EC4A000219230000
GET /v1/FCP/80000000000000010002D28E0000/011000000009EC4A00021C860000/IMG_555.JPG

Opening objects by parent webID (path) and index

This is used only for attachments or files that are small, because the entire body will be retrieved upon opening the object.

For large attachments or files, use the FCP path with the filename in it. Use the above URL open with query string Index=N.

Example:

GET /v1/FCP/80000000000000010002D28E0000?Index=27

Opening typed folders

TypedFolder=<typed folder ID>

Some common typed folder IDs:

Mailbox 1
Calendar 21
Contacts 7
My Documents 32
Shared Documents 33
Pulse 67
Bookmarks 16
Voice Greetings 20
Apps 74
Personal Apps Data 75

Example:

GET /v1/FCP/?TypedFolder=32

Opening known objects

KnownObject==<object ID>

Some common object IDs:

Preferences 6
Chat 7
System Info 8
Search 9

Example:

GET /v1/FCP/?KnownObject=6

Opening calendars

Date=YYYYMMDD
View=month | week | day
Flags=<or-ed flags of the events to retrieve>
Options=<or-ed container retrieval options>

"Date" is the date for which to retrieve events. DD is optional. The default View parameter is month.

Flags values:

Future tasks 0x01
Today list 0x02
Completed tasks 0x04
All day events 0x20
Timed events 0x40
All 0x7F

Options values:

Folders 0x0100
EventsInRange 0x0020

The Options default is 0x0020 if no options are specified.

Example:

GET/v1/FCP/?TypedFolder=21&Date=201204&Flags=0x20
GET/v1/FCP/80000000000000010002D28E0000/011000000009EC4A000219230000?Date=201106&Flags=4

Opening container objects in paged mode and selecting retrieval options

Size=<number of items per page>
Page=FIRST | NEXT | ALL
Options=<or-ed options values>
Retrieve=LIST | SUMMARY
Filter=<or-ed filter values>

The Page parameter enables you to retrieve the first page, the next page, or all pages.

The Options parameter controls which items will be retrieved:

Documents 0x1000
Complete thread 0x1001
DocsAndTextFiles 0x0080
Folders 0x0100

The Retrieve parameter controls the type of data to be retrieved:

List Regular container list items (FileInfo=1). This is the default.
Summary Summary items per thread (ThreadInfo=74)

The Filter parameter controls the type of data filtered from the data retrieved and returned to the client:

Unread 0x8000
Urgent 0x4000
Sent 0x2000
Deleted 0x1000
Outgoing 0x0800
Protected 0x0400
Unapproved 0x0200
Moved 0x0100
AutoOpen 0x0080
Addressed 0x0040
Attachments 0x0020
Subscribed 0x0010
Replicated 0x0008
Partial 0x0004
URLDoc 0x0002
Voice 0x0001

Examples:

GET/v1/FCP/011000000009EC4A000219230000?Page=FIRST&Size=100&Retrieve=LIST&Filter=0x8000
GET /v1/FCP/011000000009EC4A000219230000?Page=NEXT

Closing objects

Close
Options=<close options>

Options values:

CloseCommit 0 Normal close.
CloseAbort 1 Stop the close.
CloseSplitCommit 2 Close and change only the current instance of a recurring event.
CloseSplitCommitSubsequent 3 Close and change the current and all subsequent instances of a recurring event.

Example:

GET /v1/FCP/011000000009EC4A000219230000?Close&Options=2

Retrieving events in a given interval

/v1/FCP/<calendar path>?Event=<event webID>&Start=<start date>&End=<end date>

The path parameter is the path to the parent calendar.

The start and end parameters are the interval start and end dates, in the format Start | End=YYYYMMDD.

Example:

GET/v1/FCP/80000000000000010002D28E0000?Event=80000000000000010002D28E0000&Start=20120701&End=20120822

Retrieving threads for given threadIDs or summaryWebIDs

Thread=<threadID | summaryWebID>

The length for threadID is 16 characters. The length for summaryWebID is 28 characters.

Example:

GET /v1/FCP/80000000000000010002D28E0000/011000000009EC4A000219230000?Thread=800FFA010002D28E

Retrieving name information from the Directory

DirName=<name pattern>
CID=<client ID number>
Options=<lookup options - sum of selected options as defined bellow>

Lookup options:

Best single match 1
Conferences 2
Local names 4
Remote names 8
Include contacts 16
Include aliases 32

Examples:

GET /?DirName=Alex&Options=5
GET /?CID=32678

Retrieving name information from the Directory in paged mode

Paging can be used when expecting a large result for a Directory query. Resulting items can be retrieved in "pages" of varying size. First request defined the lookup pattern, page size and any needed retrieval options. Subsequent requests for more data reuse these parameters and only the Directory object webID need be specified in the request along with the DirName keyword.

DirName=<name pattern<
Size=<maximum number of items to retrieve - page size>
Options=<lookup options - sum of selected options as defined above>

Examples of first request:

GET /?DirName=Alex&Options=5&Size=30

Example of subsequent requests:

GET /v1/FCP/<webID od Directory object returned on first request>?DirName

Retrieving deleted objects

Deleted

Example:

GET /v1/FCP/011000000009EC4A000219230000?Deleted

Retrieving object history

History

Example:

GET /v1/FCP/011000000009EC4A000219230000?History

Retrieving profile images

The FCP URL path containing a client ID is defined as:

/v1/FCP/CID<user CID>/<profile image file-name>?Profile

Example:

GET /v1/FCP/CID99999/profile_50x67.jpg?Profile

Retrieving object information

GetInfo

Example:

GET /v1/FCP/DeskTop000000000000000000000/80000000000000010002D28E0000?GetInfo

Retrieving "Who's Online"

WhoIsOnline

Example:

GET /?WhoIsOnline

Retrieving profiles, user information forms (UIF) and user preferences

Resume&Options=<selected data option>
Resume&Index=<index value>&Options=<selected data option>
Resume&CID=<client ID value>&Options=<selected data option>

Profile parameters:

Resume Retrieves the user's own selected data.
Resume&Index Retrieves selected data of the name at index N.
Resume&CID Retrieves selected data of the user with client ID N.

The Options parameter controls which items will be retrieved. If Options parameter is omitted it will default to 3, user resume.

User preferences form 2
User resume (default) 3
User information form (UIF) 4

Note that when retrieving UIF with Options=4, you must have either "view user information" or "admin" priviledges .

Examples:

GET /?Resume
GET /?Resume&CID=32445&Options=4
GET /?Resume&Index=1

Retrieving a raw form

Form=<form name>

Example:

GET /?Form=161.html

Retrieving a list of all icon file names on the FirstClass web server

IconList

Example:

GET /?IconList

Searching

If GetForm is present, the FirstClass web server will also retrieve the search form object.

Search=<search string>&GetForm

Examples:

GET /v1/FCP/DeskTop000000000000000000000/80000000000000010002D28E0000?Search=Testing
GET /v1/FCP/DeskTop000000000000000000000/80000000000000010002D28E0000?Search=Testing&GetForm

Opening chats

To open a chat with a specific client ID, use:

Chat=<client ID>

Example:

GET /?Chat=45776

User logoffs

LogOff

Example:

GET /?LogOff

Starting asynchronous WebSocket or AJAX connections

Depending on the web browser capabilities, you can establish an asynchronous WebSocket or AJAX connection to the server.

WebSocket
AJAX

Examples:

GET /?WEBSOCKET
GET /?AJAX

Retrieving image raw data from a form field

/v1/FCP/ <path to form>?ImageField=<form field ID>

For path to form, the last element must be the form webID. The value form field ID is the form field ID of the image.

The returned value is the raw, binary image data in the HTTP response body with HTTP headers Content-type and Content-length set to correctly describe the image data.

Example:

GET /v1/FCP/DeskTop000000000000000000000/80000000000000010002D28E0000?ImageField=8027

Requesting a single-sign-on ticket (SSO) from an external ticket granting authority (TGA)

External applications that may require SSO tickets would have to be registered in FirstClass. As part of registration additonal information may be required about the external TGA such as TGA URL, credentials and SSO ticket request message.

GetTicket

Examples:

GET /v1/FCP/DeskTop000000000000000000000/<webID of registered external application>?GetTicket

Logging into FirstClass with the FirstClass single-sign-on (SSO) ticket

FirstClass SSO ticket contains all login information for a given user. No additional information is needed other than the SSO ticket to log into FirstClass.

FCTicket=<FirstClass SSO ticket>

Examples:

GET /?FCTicket=5TMd4mpgFVYiuT547pezdr2YJWe9UfYwoxZaIwOtAyj5oT$a7dkaBsN1YmC5mFQlRNGHFZljCOUZPUHtRCS33EPskAS3TijI*2fg8h*Qgb4

Authenticating the FirstClass single-sign-on (SSO) ticket

Externall applications in FC Web Server can be configured to be activated with the FC SSO authentication ticket for the logged-in user.

http(s):/application-domain-or-ip/?UserId=johndoe&FCTicket=jfsfrejoj34099tugondvkjdnf

In turn, external applications can validate this FirstClass SSO ticket against FC Web Server.

Authenticate&UserId=&FCTicket=<FirstClass SSO ticket>

Examples:

GET /?Authenticate&UserId=johndoe&FCTicket=jfsfrejoj34099tugondvkjdnf

If the ticket is valid response will be HTTP code 200. Any other response code indicates that the ticket is not valid and specified user should not be granted access to the external application

POST/PUT requests

General POST request syntax and remarks

POST requests are primarily used to send data to the FirstClass web server or FirstClass server. Data sent will be in the request body in JSON format. The general form for all POST request URLs is:

POST /?JSON HTTP/1.1

where the general syntax for all JSON requests is:

{"<command in lower case>":{
      <JSON parameters>
      }
}

All JSON mandatory parameters are in red. All optional parameters are in blue. The webid parameter always refers to the parent object, unless specified otherwise.

Some parameters are currently not used and are placeholders for future use. These parameters have a specific, constant value given in the JSON spec for a given command. For example, the reply command parameter formid has a value of 0 and should not be used (or changed).

Some optional parameters are context dependent and may be omitted altogether. For example, parameters h and v determine an object's horizontal and vertical positioning and may or may not be important and/or used in a particular application. Obviously, automated, non-UI-based applications can ignore these parameters in both input and output.

User logins (JSON)

POST /?JSON

POST message body content for JSON login:

{"login":{
      "userid":"votovic",
      "<credential type>":"<credentials>",
      "language":"<language code>"
      }
}
Credential type Credentials
password cleartext password
sha512digest base64-encoded sha-512 digest

The language code is the ISO 639 (Alpha-2) language code.

User logins (multipart/form-data)

POST / HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundarydUvSRYnRbQ82zzLR

POST message body content for cleartext password login:

------WebKitFormBoundarydUvSRYnRbQ82zzLR
Content-Disposition: form-data; name="userid"

votovic
------WebKitFormBoundarydUvSRYnRbQ82zzLR
Content-Disposition: form-data; name="password"

temp123!
------WebKitFormBoundarydUvSRYnRbQ82zzLR--
Content-Disposition: form-data; name="language"

en
------WebKitFormBoundarydUvSRYnRbQ82zzLR--

POST message body content for base64-encoded sha-512 digest login:

------WebKitFormBoundarydUvSRYnRbQ82zzLR
Content-Disposition: form-data; name="userid"

votovic
------WebKitFormBoundarydUvSRYnRbQ82zzLR
Content-Disposition: form-data; name="sha512digest"

UvSRYnRbQ82zzLRUvSRYnRbQ82zzLR7657FSD=
------WebKitFormBoundarydUvSRYnRbQ82zzLR--
Content-Disposition: form-data; name="language"

en
------WebKitFormBoundarydUvSRYnRbQ82zzLR--

Requesting a FirstClass Single-Sign-On ticket (JSON)

To use Single-Sign-On a trusted server IP must be registered with the FirstClass Server. This trusted server will be issued a FirstClass userID and password which will be used to log into FirstClass Server. This user can then request and obtain a single-sign-on ticket on behalf of ticket requesting user.

Leaving field getticket:userid blank will return a ticket for the login:userid. Hence this user does not have to be trusted as long as it has valid credentials.

POST /?JSON&ReplyAsJSON

POST message body content for JSON single-sign-on ticket request:

{"login":{
      "userid":"<userid of the trusted server>",
      "<credential type>":"<trusted server userid credentials>",
      "language":"<language code>"
      },
 "getticket":{
      "userid":"<userid requesting ticket - leave blank to obtain ticket for self>"
      }
}

Creating objects

JSON fields in green are optional and are specific to creating a mail message

{"create":{
      "webid":"<parent webID>",
      "type":<object type>,
      "name":"<object name>",
      "formid":<associated form ID>,
      "mailtocid":<message recipient CID>,
      "mailtoname":<message recipient directory name or address>,
      "subject":<message subject>,
      "body":<message body text>,
      "sendmessage":<1=send message>,
      "iconid":<associated icon ID>,
      "h":<horizontal position>,
      "v":<vertical position>
      }
}

The value object type is defined in "Object types and subtypes" below.

Sending, replying, and forwarding messages

If you use childwebid, webid is the webID of the parent container where the message is located. If you omit it, webid is the webID of the message itself.

{"send":{
      "webid":"<parent/object webID>",
      "childwebid":"<child webID>",
      "options":0,
      "delay":<delay in sec before sending>,
      "parameter":0
      }
}

{"unsend":{
      "webid":"<parent/object webID>",
      "childwebid":"<child webID>",
      }
}

{"reply":{
      "webid":"<parent/object webID>",
      "childwebid","<child webID>",
      "options":0,
      "formid":0,
      "subject":"<optional subject>",
      "body":"<optional message body>",
      "sendmessage":<any value  - message is sent>
      }
}

{"forward":{
      ">webid":"<parent/object webID>",
      "childwebid","<child webID>",
      "options":0,
      "formid":0,
      "subject":"<optional subject>",
      "body":"<optional message body>",
      "sendmessage":<any value  - message is sent>
      }
}

Message options:

Priority Normal 0x0000
Priority Urgent 0x2000
Priority Bulk 0x4000
Priority Junk 0x6000
Priority Instant 0x8000
Sensitivity Normal 0x0000
Sensitivity Personal 0x0400
Sensitivity Private 0x0800
Sensitivity Company 0x0C00
Delivery Receipt 0x0200
Read Receipt 0x0100

Moving and copying objects

If the destid parameter is omitted, the destination container is dstparentid. Otherwise, destid is the destination container.

{"objmove":{
      "srcparentid":"<source container webID>",
      "dstparentid":"<destination parent container webID>",
      "srcid":"<source item webID>",
      "dstid":"<destination container webID>",
      "h":<horizontal position>,
      "v":<vertical position>
      }
}

{"objcopy":{
      "srcparentid":"<source container webID>",
      "dstparentid":"<destination parent container webID>",
      "srcid":"<source item webID>",
      "dstid":"<destination container webID>",
      "h":<horizontal position>,
      "v":<vertical position>
      }
}

Deleting objects

If the childwebid parameter is omitted, the object specified by webid is deleted.

{"delete":{
      "webid":"<parent/object webID>",
      "childwebid":"<object to delete webID>"
      }
}

Undeleting objects

{"undelete":{
      "webid":"<parent/object webID>",
      "childwebid":"<object to undelete webID>"
      }
}

Replacing(adding)\appending body text

{"replacebody":{
      "webid":"<object webID>",
      "body":"<body text>",
      "offset":0
      }
}

{"appendbody":{
      "webid":"<object webID>",
      "body":"<body text>",
      "offset":0
      }
}

Adding/removing recipients

{"addrecipient":{
      "webid":"<object webID>",
      "type":<recipient list type>,
      "name":"<recipient name>",
      "remove":[
                 {"userwebid":<client webID 1>},
                 {"userwebid":<client webID 2>},

                 {"userwebid":<client webID n>}
                ],
      "options":<or-ed name lookup options - default all options set>,
      "pagesize":<max number of names to retrieve from Directory - default all>
      }
}

Recipient list type:

To 4
Cc 5
Bcc 14

Lookup options:

Best single match 1
Conferences 2
Local names 4
Remote names 8
Include contacts 16
Include aliases 32

You must include name, remove, or both. If both are included, the FirstClass web server will first remove specified recipients, then search for a given recipient.

Selecting a recipient

Use this syntax to select a recipient when addrecipient returns a multimatch.

{"selectrecipient":{
      "webid":"<object webID>",
      "userwebid":<client webID>,
      "where":<recipient list type>
      }
}

Recipient list type:

To 4
Cc 5
Bcc 14

Setting form fields

{"setfield":{
      "webid":"<object webID>",
      "field":[
                {"fldid":<field 1 ID>, "index":<index>, "fldtype":<field type>, "data":<field data>},
                {"fldid":<field 2 ID>, "index":<index>, "fldtype":<field type>, "data":<field data>},

                {"fldid":<field n ID>, "index":<index>, "fldtype":<field type>, "data":<field data>}
               ]
      }
}

Field types field IDs are listed in "Common field IDs and types" at the end of this document.

Deleting form fields

{"delete":{
      "webid":"<object webID>",
      "fldid":<field ID>,
      "index":<index>
      }
}

Deleting attachments as form fields

{"delete":{
      "webid":"<object webID>",
      "fldid":7,
      "childwebid":<attachment webID>
      }
}

Setting/resetting flags

{"setflag":{
      "webid":"<parent/object webID>",
      "childwebid":"<child webID>",
      "on":<0=off 1=on>
      }
}

Approve/unapprove object

{"approve":{
      "webid":"<parent/object webID>",
      "childwebid":"<child webID>",
      "on":<0=unapprove 1=approve>
      }
}

Changing passwords

Both old and new passwords have to be encrypted and base64 encoded before pasting them into the JSON request. Encryption algorithm uses the password seed value returned by the server after a successfull login. It is the "pwSeed" field value in the Login reply JSON.

Encryption algorithm is a 3 steps process:

1. Covert each password to a Pascal string where the first byte is the actual length of the password.

2. Pad the resultant Pascal string with random data up to the total length of 28 bytes.

3. XOR each byte of the password buffer with the corresponding byte of the password seed.

NOTE: If requesting password change via JSONP, resultant JSON is embedded in a GET request URL and should also be "safe-url" encoded since base64 encoded data may contain invalid URL characters.

{"changepassword":{
      "oldpass":"<old password - encrypted and base64 encoded>",
      "newpass":"<new password - encrypted and base64 encoded>"
      }
}

Sending chat text

{"chatpost":{
      "webid":"<chat object webID>",
      "text":"<chat vtext>"
      }
}

Following users

{"subscribe":{
      "cid":<client ID of user>,
      "follow":<1=follow 0=stop following>
      }
}

Subscribing to conferences

{"subscribe":{
      "webid":"<parent/object webID>",
      "childwebid":"<object webID>"
      }
}

Watching conferences

{"watch":{
      "webid":"<parent/object webID>",
      "childwebid":"<object webID>"
      }
}

Posting/replying to the Pulse

{"pulsepost":"<text>"}

{"pulsereply":{
      "text":"<reply text>",
      "webid":<pulse webID>,
      "childwebid":"<webID of pulse entry to reply to>"
      }
}

Uploading files from the browser to the server

We assume that the file was selected by the browser "file-picker" which embeds the file name and file handle into the HTTP POST request so that the web server can retrieve this information.

/v1/FCP/<path>?Upload&Options=<attach/upload options>

The path parameter is the path to the destination object. If the destination object is a container, a file is simply uploaded to that container. If the destination object is not a container type, the file is attached to the object.

Upload options:

Restart upload 1
Embedded attachment 2

Example:

POST /v1/FCP/DeskTop000000000000000000000/80000000000000010002D28E0000?Upload&Options=2

Uploading files from the browser to the server with JSON

Requesting URL is same as above except that it also contains a query keyword JSON and all the file information is contained in the JSON request of the POST request body.

/v1/FCP/<path>?Upload&JSON

{"upload":{
      "filename":"<file name>",
      "timestamp":<date-time file was created>,
      "b64data":"<entire file body base64 encoded>"
      }
}

Example:

POST /v1/FCP/DeskTop000000000000000000000/80000000000000010002D28E0000?Upload&JSON

{"upload":{
      "filename":"myfile.txt",
      "timestamp":3449386800,
      "b64data":"VGhpcyBpcyBhIHRlc3Qh"
      }
}

JSON responses

All responses to the above requests are, by default, returned by the FirstClass web server as templates rendered into HTML to be used by the Web Services client. However, third-party developers or any customized interface may request that each response be returned in JSON format. This is accomplished by adding a query parameter ReplyAsJSON anywhere in the request URL query.

Basic JSON structures returned by the FirstClass web server are described in the following sections.

All time information is given as number of seconds since January 1st 1970.

All bitmaps are represented in big-endian order.

Login reply

The following JSON is returned upon a successful login to the FirstClass server:

{
    "LOGINREPLY": {
        "DeskObjID": <object ID>,					   
        "LastLogin": <last login time (FC time)>,
        "TotalConnect": <total connected time (secs)>,
        "DailyRemaining": <daily remaining quota (secs)>,
        "LinkVersion": <link version>,
        "ServerVersion": <FC server version>,
        "ServerTZ": <FC server time-zone>,
        "SysCharSet": <FC server character set>,
        "ServerTime": <server time (FC time)>,
        "RemoteSiteID": <FC server serial number>,
        "WebSocketEnabled": <1-enabled 0-disabled>,
        "SiteName": "<object>",		
        "DeskTopWebID": "DeskTop000000000000000000000",
        "pwSeed": <"base64 encoded password seed">,
        "VKEYS": [
            {"vkey": "2085781414"},
            {"vkey": "1762394296"},
            {"vkey": "3541312797"},
            {"vkey": "1605779611"},
            {"vkey": "2221248261"},
            {"vkey": "217498030" },
            {"vkey": "408924866" },
            {"vkey": "3378976485"},
            {"vkey": "2979225874"},
            {"vkey": "2698587303"}
        ]
    }
}

Note

LOGINREPLY may contain additional data that isn't documented here because it isn't used by this API.

Field pwdSeed is used to encrypt the password in password change request. If this field is omitted from the login reply then the user is not allowed to change the password.

Single-Sign-On (SSO) ticket reply

Single-sign-on ticket reply may be a reply to a request to obtain a FirstClass ticket or a request to obtain a ticket from an external ticket granting authority. FirstClass SSO tickets are returned as raw tickets in the "ticket" field. Many other external ticket granting authorities return URL embedded tickets in the "url" field. SSO reply will contain usually one of the two. However, some other external ticket granting authorities may require different formats. They will be documented as FCWS develops support for such SSO systems. 

{"SSO":{
      "userid":"<userid of the ticket requestor>",
      "url":"<url for single-sign-on with embedded ticket>",
      "ticket":"<raw ticket>"
      }
}

List items - MLITEM (MYMLITEM)

List items are condensed information on a particular object within a container so that its information can be displayed in the parent container in short, list form. List item can be sent unsolicited as part of a notification of a change on a particular object or its parent. Note that list item may not contain all fields except mandatory ones.

{"<item type>":{
      "<operation>":{
            "ShortInfo":{
                          "objType":<object type>,
                          "subType":<object subtype>,
                          "modDate":<date modified>,
                          "status":<status bits>,
                          "locationV":<vertical position>,
                          "locationH":<horizontal position>,
                          "iconID":<icon ID>,
                          "size":<object size in Kb>,
                          "unreadCount":<unread items>
                          },
            "parentID":"<parent webID>",
            "webID":"<object webID>",
            "index":<object index>,
            "objAttributes":<object attributes bits>,
            "dirAttributes":0 <directory attributes bits - not used>,
            "form field ID":<form field value>,
                 .
                 .
            "form field ID":<form field value>
            }
      }
}

Object types and subtypes are listed in "Object types and subtypes" at the end of this document.

Item type ::= MYMLITEM - list item of the current object (e.g. Mailbox)
              MLITEM - list item of the object within the current object (e.g. message 1)

Operation is mostly used for live notifications to indicate the disposition of the list item for which a notification is being sent.

Operation ::= ADD - new item
              UPDATE - existing item
              DELETE - removed item

Status bits (16-bits big-endian):

Unread 0x8000
Urgent 0x4000
Sent 0x2000
Deleted 0x1000
Outgoing 0x0800
Protected 0x0400
Unapproved 0x0200
Moved 0x0100
Auto open 0x0080
Addressed 0x0040
Attachments 0x0020
Subscribed 0x0010
Voice 0x0001

Object attribute bits (32-bits big-endian):

User class 0x00FF0000 (masked 8 bits - 1=Regular user 2=Conference 5=Remote user 8=Remote name)
Logged on 0x00008000

List items can have some embedded field data which may or may not be a duplicate of form data in the actual object.

For a detailed description of form field values, see "Form data" below.

List items data store (MLDS)

List items for a specific object are returned in an array of list items called the list item data store (MLDS). the list data store is never sent standalone but as a followup to a generalized response. In this case, the JSON object is always preceded by a MYMLITEM JSON object that identifies the target object.

{"MLDS":[<MLITEM 1>,<MLITEM 2>,...<MLITEM N> ]}

Form data (FORMDATA)

Form data is an array of field IDs and corresponding values associated with a particular object. Each object can be viewed as a form containing field data. Form data for each object is returned in the JSON structure FORMDATA. Form field data is never sent standalone but as a follow-up to a generalized response. In this case, the JSON object is always preceded by a MYMLITEM JSON object that identifies the target object.

{"FORMDATA":<forms-data>}

<forms-data>   ::= <field 1 data>,<field 2 data>,....<field N data>
<field N data> ::= "field ID":<field value>
<field value>  ::= <base value> | <indexed values> | <sparse indexed values>
<base value>   ::= "<string field>" | <number field> | {"b64":"<base64 encoded field>"}

This format assumes that all index values are 'positional' (contiguous) starting with 0 and up to N.

<indexed value>  ::= [<base value 0>,<base value 1>,....<base value N>]

This format assumes that all index values are 'sparse' (non-contiguous). Each base value has a key which is the index value itself.

<sparse indexed value>  ::= {"<index 0 value>":<base value 0>,"<index 1 value>":<base value 1>,...."<index N value>":<base value N>}

Forms (FORM)

An entire rendered form can be sent to the client. Raw forms can be either solicited or unsolicited. Solicited forms are explicitly requested by GET /?Form=<form name>. Unsolicited forms are forms that are sent to the client as a result of events on the server (e.g. calendar event reminder popup).

Unsolicited form JSON format:

{"FORM":{
      "webid":"<form object webID>",
      "data":"<base64 encoded rendered form>"
      }
}

Solicited form JSON format does not have a webID parameter since the form object does not exist on the server:

{"FORM":{
      "data":"<base64 encoded rendered form>"
      }
}

Response status (ERROR)

All JSON requests issued by the server will receive an HTTP response with the appropriate HTTP status code as well as a JSON error reply as part of the response body.

{"ERROR":{
      "code":<error code>,
      "msg":"<error message>",
      "status":"<status message>"
      "VKEYS": [{"vkey": "<new validation key>"}],
      }

<error code>         ::= FCP protocol error code
<error message>      ::= FCP protocol error localized message
<status message>     ::= request-specific status message
<new validation key> ::= a new validation key for the client to use in JSONP embedded POST request

Session data (SESSION)

The general syntax is:

{"SESSION":{
      "data type": set of data values
      }
}

Data types are metrics, status, or command.

{"SESSION":{
      "metrics":{
                  "users":<number of users logged in>,
                  "requestCount":<number of requests in measured interval>,
                  "requestTime":<total request time service time in measured interval (secs)>,
                  "elapsedTime":<interval (secs)>
                  }
      }
}

{"SESSION":{
      "status":"timeout" | "disconnected",
      "message"<optional localized message>":
      }
}

{"SESSION":{
      "command":"logoff" | "warnLogoff"
      "parameter":<numeric logoff reason code>
      "message"<localized logoff reason message>":
      }
}

General JSON response syntax

General JSON response syntax for most of the requests is a series of concatenated JSON formats as described above.

{ "MYMLITEM":MLITEM of the target object,
  "NFILES":<number of files/items in object>,
  "RIGHTS":<rights bitmap>,
  "BODY":<base64 encoded object body>,
  "FORMDATA": <forms-data>,
  "MLDS":[array of {MLITEM} JSON objects]
}

Object types and subtypes

Object types

oDeskTop 0
oConference 1
oFolder 2
oConfItem 3
oMessage 4
oText 5
oFile 6
oDirList 7
oProfile 8
oUserList 9
oEFolder 10
oACL 11
oForm 12
oHistory 13
oChat 14
oInviteChat 15
oSysInfo 16
oFormDoc 17
oBackLink 18
oHitList 19
oMemForm 20
oUser 21
oDocument 22
oWorkForm 23
oMailBox 24
oPGFolder 25
oGWFolder 26
oMailListFolder 27
oDeskTopFolder 28
oArchive 29
oModelFolder 30
oPermStationery 31
oTempStationery 32
oGenDirSync 33
oGenSiteSync 34
oFCFile 35
oRemoteAdmin 36
oFirmLink 37
oSynData 38

Object subtypes

Mailbox 1
Contacts 7
Calendar 21
Resource calendar 22
Group calendar 28
My Documents 32
Shared Documents 33
Communities 66
Pulse 67

Form field types

String 0
Checkbox 6
Short 7
Long 14
PopupList 80
MacText 100
MacPicture 101
MacSound 102
GIF 103
WinBMP 104
WinWAV 105
Byte 106
Text 107
Sound 108
Image 109
Button 110
StyleData 111
ClearField 112
SetListCount 113
Attributes 114
SetFocus 115
Select 116
FormAction 117
PropertyStream 118
Float 119
Double 120
ShortInfo 121
Binary 122
RequestData 123
SetSelection 124
FCName 125
History 126
Remove 127
MediaStream 128
JPEG 129
HTML 130
INT64 131
Result 132
ObjID 133

Common form field IDs and types

Well-known field IDs can be considered reserved field IDs that define a very specific field, its type and meaning in any FirstClass form.

Documents and messages

To 4 string
Copy 5 string
Body 6 string
From 8 string
Subject 9 string
Blind copy 14 string
Thread ID 38 long
Message ID 39 binary
Name 8010 string
Thumbnail 1001 binary

Calendar events and tasks

Start date-time 1001 long
Duration in seconds 1002 long
Color 1003 long
Repeat until date-time 1004 long
Reminder (seconds before event) 1005 long
Repeat type
0=None   11=Daily   12=Weekly   13=Monthly   14=Yearly		 1007 long
Repeat interval type 1 1159 long
Repeat interval type count 1158 long
Reminder control
0=Off   1=Reminder owner   2=Remind all participants		 1008 long
Description 7 string
Location 1009 string
Category 8021 string
Busy time
0=Busy   1=Tentative   2=Out of office   10=Free		 1010 long
Visibility
0=Normal   1=Personal   2=Private   3=Company		 34 long
All Day 59 checkbox
Task 1011 checkbox
Task status
0= Notstarted   1=Completed   2= Inprogress   3=Waiting   4=Deferred		 1012 long
Task completed date 1018 long

1Repeat interval types:

Repeat type Interval types
Daily 0=N days   1=N set weekdays   2=N weekends
Weekly 0=N weeks on same weekday   1=N weeks on set weekdays
Monthly 0=N months on same day   1=N months on same weekday
Yearly 0=N years on same date   1=N years on same weekday of same month

Access rights

Edit permissions 0x0001
Moderator 0x0002
Delete 0x0004
Create 0x0008
Edit 0x0010
Write 0x0020
Edit info 0x0040
Approve 0x0080
Delete own 0x0100
Read 0x0200
Search 0x0400
Send 0x0800
Open 0x1000
Download 0x4000
View permissions 0x8000
View history 0x10000
Revert 0x20000
Enable 0x40000
Get info 0x80000
Open by name 0x100000
View dates 0x200000



Copyright ©2013 OpenText Corporation